<!DOCTYPE html>
<html lang="en">
	<head>
		<title>Recaf - modern bytecode editor</title>
		<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
		<meta name="viewport" content="width=device-width">
		<meta name="description" content="Recaf is a modern java bytecode editor using Objectweb's ASM and JavaFX.">
		<meta name="keywords" content="java,bytecode,editor,recaf,reverse engineering">
		<link rel="icon" type="image/x-icon" href="favicon.ico"/>
		<link href="https://fonts.googleapis.com/css?family=Roboto:300" rel="stylesheet">
		<link rel="stylesheet" href="css/style.css">
		<link rel="stylesheet" href="css/code.css">
	</head>
	<body>
		<header>
			<div class="beam container-wide">
				<div class="box-left">
					<a href="index.html"><div class="logo"></div></a>
				</div>
				<div class="box-right">
					<nav>
						<a href="index.html">Home</a>
						<a href="documentation.html" class="current">Documentation</a>
						<a href="features.html">Features</a>
						<a href="https://github.com/Col-E/Recaf">Github</a>
					</nav>
				</div>
			</div>
		</header>
		<section id="content">
			<h1 id="gs">Getting Started</h1>
			<h3 id="gs-r">Requirements</h3>
			<p><b>Java 8:</b> Releases on Github will be targeting Java 8. <i>No extra steps are neccesary to run</i>.</p>
			<p><b>Java 9/10:</b> <i>Unsupported</i>, either use Java 8 or update to Java 11+</p>
			<p><b>Java 11+:</b> <a href="jigsaw.html">Supported</a>. Recaf can patch itself to fix missing JDK 11 dependencies.</p>
			<h3 id="gs-ru">Running &amp; Updates</h3>
			<p>To get the latest version of Recaf you can either download the source code and compile with maven or <a href="https://github.com/Col-E/Recaf/releases">grab a binary from the releases page</a>.</p>
			<p>As a jar file you can double click it to run Recaf. However it is reccomended that you launch via command line so you can specify the JDK <span class="code">java</span> executable. Doing this will unlock additional features that rely on JDK functionality <i>(tools.jar)</i>. For example on windows you would use the following command:<br> <span class="code">"C:\Program Files\Java\jdk1.8.0_202\bin\java.exe" -jar recaf.jar</span></p>
			<p><b>Note:</b> To ensure the classpath contains the contents of <span class="code">jdk\lib\tools.jar</span> copy it into your <span class="code">jdk\jre\lib\ext</span> folder.</p>
			<p><b>Note:</b> You can automate opening files via command line: <span class="code">java -jar recaf.jar -i MyJar.jar -c com/example/MyClass</span><p>
			<p><b>Note:</b> When launching Recaf you will be notified about updates as they come out. You can change this behavior in the <a href="#uisw-c">config menu</a>.</p>
			<!-- --->
			<h1 id="uimw">User Interface: Main Window</h1>
			<h3 id="uimw-nt">Navbar &amp; Toolbar</h3> 
			<img class="ci" src="screenshots/ui-navbar.png">
			<p>Across the top of the window are two bars, the Navbar and the Toolbar. The Navbar is the first bar and is a series of text drop-down menus.</p>
			<ul>
				<li><b>File</b></li>
				<ul>
					<li><b>Load</b>: Open a file <i>(class, jar)</i></li>
					<li><b>Export</b>: Save modifications <i>(Same type as input)</i></li>
				</ul>
				<li><b>Search</b>: Open <a href="#uisw-s">search menu</a></li>
				<li><b>Config</b>: Open <a href="#uisw-c">config menu</a></li>
				<li><b>History</b></li>
				<ul>
					<li><b>Create save-state</b>: Save modifications in memory.</li>
					<li><b>View states</b>: Open save-state manager, which allows rolling back to a previous save-state.</li>
				</ul>
				<li><b>Attach</b>: Open <a href="#uisw-a">attach window</a> <i>(JDK-only feature)</i></li>
			</ul>
			<p>The second bar is the Toolbar which is used for quick access to common functions. You can hide this bar in the <a href="#uisw-c">config menu</a>.</p>
			<ul>
				<li><b>Load</b>: Open a file <i>(class, jar)</i></li>
				<li><b>Export</b>: Save modifications <i>(Same type as input)</i></li>
				<li><b>Create save-state</b>: Save modifications in memory.</li>
				<li><b>Search</b>: Open <a href="#uisw-s">search menu</a></li>
				<li><b>Config</b>: Open <a href="#uisw-c">config menu</a></li>
			</ul>
			<h3 id="uimw-ft">File Tree</h3>
			<img class="ci" src="screenshots/ui-filetree.png">
			<p>The file tree shows the current contents of the loaded program. The icons next to class names indicate the access modifiers of the class <i>(Blue for interface, brown for enum, green for standard class. Modifiers such as abstract, synthetic, etc. are added as overlays)</i>. Once the tree is selected you can navigate the tree with the arrow keys or the mouse. Pressing <span class="code">enter</span> or double clicking will open a class. You can also drag and drop a file into this area to load a new program.</p>
			<h3 id="uimw-mp">Main Panel</h3>
			<img class="ci" src="screenshots/ui-mainpanel.png">
			<p>The main panel contains all of the information about a class. Across the top is a series of currently opened classes. Below that is a panel for the current class. Each class has three tabs, one for class information, then two more for the field and method tables. At the bottom of this panel is a logging panel. This will include informative messages about current actions as well as error messages <i>(Which can be expanded by clicking on the line)</i>.
			<h3 id="uimw-k">Keybinds</h3>
			<p>Global keybinds are activated by holding <span class="code">control</span> and an additonal key. The current set of keybinds can be found on the <a href="options.html#keybinds">options page</a>. All of the keybinds can be modified or disabled in the <a href="#uisw-c">config menu</a>.</p>
			<!-- --->
			<h1 id="uisw">User Interface: Secondary Windows</h1>
			<h3 id="uisw-s">Search</h3>
			<img class="ci" src="screenshots/uisw-search.png">
			<p>The search window allows for multiple types of searches across the entire loaded program. Not all parameters are required when searching. For example if you wish to find all references to the class <span class="code">java/io/File</span> use the references search and only specify the owner as <span class="code">java/io/File</span>. This will show all references to the class. If you wish to narrow results down to only boolean function calls then you could specify the descriptor as <span class="code">()Z</span>. The same approach applies to all multi-parameter search types.</p>
			<ul>
				<li><b>Strings:</b> Search for string constants</li>
				<ul>
					<li><b>Text:</b> The text to search for.</li>
					<li><b>Match mode:</b> How to match against the text.</li>
					<ul>
						<li><b>Contains:</b> Matches will contain the given text.</li>
						<li><b>Starts with:</b> Matches will start with the given text.</li>
						<li><b>Ends with:</b> Matches will end with the given text.</li>
						<li><b>Equality:</b> Matches will exactly match the given text.</li>
						<li><b>Regex:</b> Matches will satisfy the regex pattern given in text.</li>
					</ul>
					<li><b>Case sensitive:</b> Modifier for match mode, force matches to be case-sensitive. Value is overriden if match mode is set to regex.</li>
					<li><b>Ignored prefixes:</b> A list of class prefixes to ignore. Specifying a name in this list will exclude all results from that class or package.</li>
				</ul>
				<li><b>Values:</b> Search for numeric constants</li>
				<ul>
					<li><b>Value:</b> Numeric value to search for.</li>
					<li><b>Ignored prefixes:</b> A list of class prefixes to ignore. Specifying a name in this list will exclude all results from that class or package.</li>
				</ul>
				<li><b>Declarations:</b> Search for declared members</li>
				<ul>
					<li><b>Owner:</b> Class name that defines a member.</li>
					<li><b>Name:</b> Name of defined member.</li>
					<li><b>Descriptor:</b> Descriptor of defined member.</li>
					<li><b>Match mode:</b> How to match against the text inputs <i>(Owner, name, descriptor)</i>.</li>
					<ul>
						<li><b>Contains:</b> Matches will contain the given text.</li>
						<li><b>Starts with:</b> Matches will start with the given text.</li>
						<li><b>Ends with:</b> Matches will end with the given text.</li>
						<li><b>Equality:</b> Matches will exactly match the given text.</li>
						<li><b>Regex:</b> Matches will satisfy the regex pattern given in text.</li>
					</ul>
					<li><b>Case sensitive:</b> Modifier for match mode, force matches to be case-sensitive. Value is overriden if match mode is set to regex.</li>
					<li><b>Ignored prefixes:</b> A list of class prefixes to ignore. Specifying a name in this list will exclude all results from that class or package.</li>
				</ul>
				<li><b>References:</b> Search for references to members</li>
				<ul>
					<li><b>Owner:</b> Class name that defines a referenced member.</li>
					<li><b>Name:</b> Name of referenced member.</li>
					<li><b>Descriptor:</b> Descriptor of referenced member.</li>
					<li><b>Match mode:</b> How to match against the text inputs <i>(Owner, name, descriptor)</i>.</li>
					<ul>
						<li><b>Contains:</b> Matches will contain the given text.</li>
						<li><b>Starts with:</b> Matches will start with the given text.</li>
						<li><b>Ends with:</b> Matches will end with the given text.</li>
						<li><b>Equality:</b> Matches will exactly match the given text.</li>
						<li><b>Regex:</b> Matches will satisfy the regex pattern given in text.</li>
					</ul>
					<li><b>Case sensitive:</b> Modifier for match mode, force matches to be case-sensitive. Value is overriden if match mode is set to regex.</li>
					<li><b>Ignored prefixes:</b> A list of class prefixes to ignore. Specifying a name in this list will exclude all results from that class or package.</li>
				</ul>
				<li><b>Opcode patterns:</b> Search for patterns in method instructions</li>
				<ul>
					<li><b>Opcodes:</b> A list of opcodes to match. You may specify additional information by seeing how Recaf displays existing opcodes.</li>
					<li><b>Ignored prefixes:</b> A list of class prefixes to ignore. Specifying a name in this list will exclude all results from that class or package.</li>
					<li><b>Match mode:</b> How to match against the opcode pattern text</li>
					<ul>
						<li><b>Contains:</b> Matches will contain the given text.</li>
						<li><b>Starts with:</b> Matches will start with the given text.</li>
						<li><b>Ends with:</b> Matches will end with the given text.</li>
						<li><b>Equality:</b> Matches will exactly match the given text.</li>
						<li><b>Regex:</b> Matches will satisfy the regex pattern given in text.</li>
					</ul>
					<li><b>Case sensitive:</b> Modifier for match mode, force matches to be case-sensitive. Value is overriden if match mode is set to regex.</li>
				</ul>
			</ul>
			<img class="ci" src="screenshots/uisw-search-res.png">
			<p>When a search is completed the results are shown in a format similar to the file tree. It is navigated in the same way. The only difference is that members and opcodes can be shown in this tree. All of which can be selected and opened. When an item is opened it will open the class in the main panel and open any neccesary secondary window <i>(If you select a member or opcode for instance)</i>.</p>
			<h3 id="uisw-c">Config</h3>
			<img class="ci" src="screenshots/uisw-config.png">
			<p>The config window groups together all of the different options. For descriptions of each option you can hover over the name or read the <a href="options.html">option table here</a>. Some options may require a restart to come into effect.</p>
			<h3 id="uisw-h">History</h3>
			<img class="ci" src="screenshots/uisw-history.png">
			<p>The history window shows a list of all classes with save-states. When one of the classes is selected you can see the existing save states in order of when they were created. You can revert any changes to the most recent state by clicking the <i>"Revert to last"</i> button. This will remove the state from the list and discard any changes made after that save-state was created.</p>
			<h3 id="uisw-a">Attach</h3>
			<img class="ci" src="screenshots/uisw-attach.png">
			<p>The attach window shows running java processes. Selecting one and clicking the button below <i>(which changes to match the selected JVM process)</i> will load Recaf as a Java agent in the process. This will allow you to modify existing code in the process while it is running. When Recaf opens as an agent you can save your changes to the live applicaiton via <i>"File->Apply changes"</i>. You can dump the classes of the attached program with the standard export functionality.</p>
			<p><b>Note:</b> Limitations may apply depending on the way instrumentation is implemented in whichever Java virtual machine you have installed. Typically the only limitation is the inability to add new fields and method definitions to classes. Everything can be modified, but no new definitions may be added.</p>
			<p><b>Note:</b> It is also worth mentioning that method redefinitions only take affect after following calls to the method. For instance you cannot call a method with an infinite loop and edit in an exit condition.</p>
			<!-- --->
			<h1 id="uie">User Interface: Editors</h1>
			<h3 id="uie-cp">Class Panel</h3>
			<img class="ci" src="screenshots/uie-class.png">
			<p>The class panel contains class information. For descriptions of each of the values you can hover over the label. All items are updated as you modify the values. Clicking any of the <i>"Edit"</i> will open an appropriate editor window.</p>
			<h4 id="uie-cp-d">Decompile</h4>
			<img class="ci" src="screenshots/uie-class-decompile.png">
			<p>At the bottom of the Class Panel a decompile button will show the decompiled code using <a href="http://www.benf.org/other/cfr/">CFR</a>. If you are running recaf via the JDK you can also edit this code and recompile it. To recompile the decompiled code, right click and select <i>"Recompile"</i>. Since decompilation is not always perfect this may not be viable in complex or obfuscated classes, but works very well in small and simplistic classes.</p>
			<p>This window also attempts to use the JavaParser api to detect referenced classes, fields, and methods. This allows the the following functionality:</p>
			<ul>
				<li>Jumping to member definitions</li>
				<li>Searching for member references</li>
				<li>Searching for class references</li>
			</ul>
			<p>The code parser also allows this detection in method bodies. Most items will support some action when right-clicked.</p>
			<h4 id="uie-cp-f">Fields Table</h4>
			<img class="ci" src="screenshots/uie-class-fields.png">
			<p>The fields table shows all fields in the class in a sortable table. The colums are the field's access modifiers, type, and name. Clicking on the category header will sort the table by that value.</p>
			<p>To edit a field, double-click the field's row.</p>
			<p>To add or remove a field, right click the table <i>(anywhere)</i> and select <i>"Add"</i> or <i>"Remove"</i> respectively.</p>
			<p>To search for where the field is referenced in the program, right click the field's row and select <i>"References"</i> from the menu.</p>
			<h4 id="uie-cp-m">Methods Table</h4>
			<img class="ci" src="screenshots/uie-class-methods.png">
			<p>The methods table shows all methods in the class in a sortable table. The colums are the methods's access modifiers, return type, name, and argument types. Clicking on the category header will sort the table by that value.</p>
			<p>To edit a method, double-click the method's row.</p>
			<p>To add or remove a method, right click the table <i>(anywhere)</i> and select <i>"Add"</i> or <i>"Remove"</i> respectively. As an alternative to adding a method, you can also select <i>"Duplicate"</i> to copy an existing method.</p>
			<p>To search for where the method is referenced in the program, right click the method's row and select <i>"References"</i> from the menu.</p>
			<p>To see the method's decompiled code, select <i>"Decompile"</i>. This will decompile the method using <a href="http://www.benf.org/other/cfr/">CFR</a>.
			<p>To edit a method's code, select either <i>"Edit instructions"</i> or <i>"Edit with assembler"</i> from the menu. Selecting <i>"Edit instructions"</i> will open the <a href="#uie-mw-i">Instructions window</a>. Selecting <i>"Edit with assembler"</i> will open the <a href="#uie-mw-as">Assembler window</a>. </p>
			<h3 id="uie-fw">Field Window</h3>
			<img class="ci" src="screenshots/uie-field.png">
			<p>The field window shows a field's information. This includes anything pertaining to the definition of the field, like the access modifiers, name, type descriptor, and annotations. For primitive fields <i>(int, long, etc.)</i> the <i>Default<u>V</u>alue</i> can also be specified. Object types can not have default values set in this field and instead must be defined in a class's constructor or static block <i>(depending on the field's access modifiers)</i>.</p>
			<h4 id="uie-fw-a">Annotations</h4>
			<img class="ci" src="screenshots/uie-field-anno.png">
			<p>Fields can have different kinds of annotations applied to them, but they all share the same window. To remove an annotation right click it and select <i>"Remove"</i>. To add an annotation specify the name using an internal descriptor format (<span class="code">Lyour/type/Here;</span>) and click the <i>"Add"</i> button. Specifying attribute data is not yet complete.</p>
			<h3 id="uie-mw">Method Window</h3>
			<img class="ci" src="screenshots/uie-method.png">
			<p>The method window shows a method's information. This includes anything pertaining to the definition of the method, like the access modifiers, name, type descriptor, instructions, local variables, and annotations.</p>
			<h4 id="uie-mw-e">Exceptions</h4>
			<img class="ci" src="screenshots/uie-method-exceptions.png">
			<p>The exceptions window shows all exceptions that apply to the method. To remove an exception right click it and select <i>"Remove"</i>, or select it and hit the <span class="code">Delete</span> key. To add a new exception enter the full name of the exception class and hit the <i>"Add"</i> button.</p>
			<h4 id="uie-mw-p">Parameters</h4>
			<img class="ci" src="screenshots/uie-method-parameters.png">
			<p>The parameters window shows parameter variables with their access modifiers. This list can be empty even when methods have parameters.</p>
			<h4 id="uie-mw-a">Annotations</h4>
			<p>Methods can have different kinds of annotations applied to them, but they all share the same window. To remove an annotation right click it and select <i>"Remove"</i>, or select it and hit the <span class="code">Delete</span> key. To add an annotation specify the name using an internal descriptor format (<span class="code">Lyour/type/Here;</span>) and click the <i>"Add"</i> button. Specifying attribute data is not yet complete.</p>
			<h4 id="uie-mw-tc">Try-Catch</h4>
			<img class="ci" src="screenshots/uie-method-trycatch.png">
			<p>The try-catch window shows all try-catch block in the method's instructions. To edit the blocks ranges you may click the label buttons and select a new label from the dropdown menu. To insert a new try-catch block fill out the label buttons at the bottom then specify an exception type. Click <i>"Add"</i> to submit the new try-catch block. The fields in order are:</p>
			<ul>
				<li><b>Start index:</b> The first frame before where the <span class="code">try</span> appears. This marks the beginning of the <span class="code">try</span> block.</li>
				<li><b>End index:</b> The final frame before where the <span class="code">catch</span> appears. This marks the end of the <span class="code">try</span> block.</li>
				<li><b>Handler index:</b> The first frame after where the <span class="code">catch</span> appears. This marks the beginning of the <span class="code">catch</span> block.</li>
			</ul>
			<h4 id="uie-mw-lv">Local Variables</h4>
			<img class="ci" src="screenshots/uie-method-variables.png">
			<p>The local variable window shows all variables in the method. Like other windows hovering over the input fields at the bottom will tell you what they are. For reference they are:</p>
			<ul>
				<li><b>Index:</b> The variable's index.</li>
				<li><b>Name:</b> The variable's name. Only used as debug information.</li>
				<li><b>Type descriptor:</b> The variable's declared type.</li>
				<li><b>Type signature:</b> The variable's generic declared type. Optional and only used as debug information.</li>
				<li><b>Begin index:</b> The first frame before the variable is referenced.</li>
				<li><b>End index:</b> The final frame after the variable is done being referenced.</li>
			</ul>
			<h4 id="uie-mw-d">Decompile</h4>
			<img class="ci" src="screenshots/uie-method-decompile.png">
			<p>Methods can be decompiled via the right-click menu in the <a href="#ui-cp-m">method panel</a>. If you update a method's bytecode while the method decompilation window is open, the decompilation will update to reflect your changes. Unlike the <a href="#uie-cp-d">full-class decompile window</a>, you cannot recompile the code in this window.</p>
			<h4 id="uie-mw-as">Assembler</h4>
			<img class="ci" src="screenshots/uie-method-assembler.png">
			<p>The assembler window is a hybrid of the <a href="#uie-mw-d">decompile</a> window and the <a href="#uie-mw-i">instructions</a> window. For a full guide on its functionality please see the <a href="assembler.html">assembler guide</a>.</p>
			<h4 id="uie-mw-i">Instructions</h4>
			<img class="ci" src="screenshots/uie-method-instructions.gif">
			<p>The instructions window is where you edit a method's opcodes. Right clicking an opcode will present some options:</p>
			<ul>
				<li><b>Edit:</b> Show the opcode's properties window. <i>(Also done via double clicking an opcode)</i></li>
				<li><b>Show stack/locals:</b> Open a window that shows the stack. It will update to show you the current stack value as you select different opcodes in the method.</li>
				<li><b>Shift up:</b> Move the selected opcode(s) up.</li>
				<li><b>Shift down:</b> Move the selected opcode(s) down.</li>
				<li><b>Save as block:</b> Save the selected opcodes as a <i>"block"</i>. This will let you paste the block anywhere else that you like. Saved blocks are stored in the config directory's <span class="code">rc_blocks.json</span> file. You can edit, remove, and create your own blocks in this file.<br><i>(You need to select multiple opcodes for this option to appear.)</i></li>
				<li><b>Insert block:</b> Opens the block window and prompts you to select a block to insert into the method before or after the selected opcode.</li>
				<li><b>Insert:</b> Add a new opcode before or after the selected opcode(s). Opens the opcode creation window.</li>
				<li><b>Insert with assembler:</b> Add new opcodes after the selected opcode(s). Opens the opcode <a href="#uie-mw-as">assembler window</a>.</li>
				<li><b>Remove:</b> Remove the selected opcode(s).</li>
			</ul>
			<p>As seen in the animation above, selecting different opcodes results in some highlights appearing.</p>
			<ul>
				<li>When selecting an opcode that references an indexed variable, all other opcodes referencing that variable are highlighted.</li>
				<li>When selecting a jump opcode the potential destinations are highlighted.</li>
				<ul>
					<li>Green is where the program will jump to if the jump operation succeeds.</li>
					<li>Red is where the program will jump to if the jump operation fails.</li>
				</ul>
				<li>When selecting a switch opcode the case destinations are highlighted.</li>
				<li>When selecting a label any opcode that lists it as a potential destination <i>(Jumps or switches)</i> those opcodes will be highlighted.</li>
			</ul>
			<img class="ci" src="screenshots/uie-method-opcodetyping.gif">
			<p>For opcode editing and insertion windows, opcodes will be presented in a drop-down menu. You can shorten the menu's list by typing the name of the opcode you want. Non-matching items will be temporarily hidden.</p>
			<p></p>
			<h4 id="uie-mw-sw">StackWatcher</h4>
			<img class="ci" src="screenshots/uie-method-stack.gif">
			<p>The StackWatcher window can be opened by right-clicking any opcode and selecting <i>"Show Stack/Locals"</i>. It shows the current value of the stack and local tables based on the current selected opcodes in a method's instructions window. As seen in the animation as the selection moves through the code, the stack is updated. When a local-variable store opcode is called, the stack is shifted over into the local column.</p>
			<h4 id="uie-mw-b">Blocks</h4>
			<img class="ci" src="screenshots/uie-method-instructions-blocks.png">
			<p>The blocks window shows the currently saved blocks in a 2xN grid. You can click on the block title to auto-complete the text-input below. Clicking <i>"Load"</i> will insert the specified block into the method.</p>
			<p>For quicker access and non-permanant storage, you can alternatively use the copy and paste keys to directly select opcodes and paste them elsewhere.</p>
			<h4 id="uie-mw-v">Verification</h4>
			<img class="ci" src="screenshots/uie-method-instructions-verify.png">
			<p>All changes are run through a verification process. If a change to a method's instructions results in unverifiable code the instruction that caused the verification failure is highlighted and the error is shown. If you attempt to export your program with errors then the larger verification window is displayed. It shows the method in question along with some additional information about the verification failure to show what the issue is.</p>
			<h1 id="c">Customization &amp; Plugins</h1>
			<p>Recaf uses JavaFX which allows the user interface to be styled with CSS. For more information about changing the visual style of recaf see the <a href="theme.html">theme guide</a>.</p>
			<p>Additional functionality can be added to Recaf through the plugin system. To learn about using and creating plugins see the <a href="plugins.html">plugin guide</a>.</p>
		</section>
	</body>
</html>